.TH std::basic_filebuf::open 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_filebuf::open \- std::basic_filebuf::open

.SH Synopsis
   basic_filebuf* open( const char* s, std::ios_base::openmode mode   \fB(1)\fP
   );
   basic_filebuf* open( const std::string& str,                       \fB(2)\fP \fI(since C++11)\fP
   std::ios_base::openmode mode );
   basic_filebuf* open( const std::filesystem::path& p,               \fB(3)\fP \fI(since C++17)\fP
                        std::ios_base::openmode mode );
   basic_filebuf* open( const std::filesystem::path::value_type* s,   \fB(4)\fP \fI(since C++17)\fP
                        std::ios_base::openmode mode );

   If the associated file was already open (is_open() != false), returns a null pointer
   right away.

   Otherwise, opens the file with the given name (s
   , p.c_str()
   \fI(since C++17)\fP or str.c_str(), depending on the overload). std::ios_base::openmode
   values may be written as, e.g., std::ios_base::out | std::ios_base::app.

   Overload \fB(4)\fP is only provided if std::filesystem::path::value_type is  \fI(since C++17)\fP
   not char.

   The file is opened as if by calling std::fopen with the second argument (file access
   mode) determined by the result of mode & ~std::ios_base::ate as follows, open()
   fails if the result is not some combination of flags shown in the table:

        mode & ~std::ios_base::ate         std::fopen    Action if file  Action if file
   binary in out trunc app noreplace         access      already exists  does not exist
                           (since C++23)      mode
   -      +  -   -     -   -             "r"                             Failure to
   +      +  -   -     -   -             "rb"           Read from start  open
   -      +  +   -     -   -             "r+"                            Error
   +      +  +   -     -   -             "r+b"
   -      -  +   -     -   -             "w"
   -      -  +   +     -   -
   +      -  +   -     -   -             "wb"           Destroy contents Create new
   +      -  +   +     -   -
   -      +  +   +     -   -             "w+"
   +      +  +   +     -   -             "w+b"
   -      -  +   -     -   +             "wx"
   -      -  +   +     -   +
   +      -  +   -     -   +             "wbx"          Failure to open  Create new
   +      -  +   +     -   +
   -      +  +   +     -   +             "w+x"
   +      +  +   +     -   +             "w+bx"
   -      -  +   -     +   -             "a"
   -      -  -   -     +   -
   +      -  +   -     +   -             "ab"
   +      -  -   -     +   -                            Write to end     Create new
   -      +  +   -     +   -             "a+"
   -      +  -   -     +   -
   +      +  +   -     +   -             "a+b"
   +      +  -   -     +   -

   If the open operation succeeds and (openmode & std::ios_base::ate) != 0 (the ate bit
   is set), repositions the file position to the end of file, as if by calling
   std::fseek(file, 0, SEEK_END), where file is the pointer returned by calling
   std::fopen. If the repositioning fails, calls close() and returns a null pointer to
   indicate failure.

.SH Parameters

   s, str, p - the file name to open; s must point to a null-terminated string
   openmode  - the file opening mode, a binary OR of the std::ios_base::openmode modes

.SH Return value

   this on success, a null pointer on failure.

.SH Notes

   open() is typically called through the constructor or the open() member function of
   std::basic_fstream.

.SH Example


// Run this code

 #include <fstream>
 #include <iostream>

 int main()
 {
     std::string filename = "Test.b";
     std::filebuf fb;

     // prepare a file to read
     double d = 3.14;
     if (!fb.open(filename, std::ios::binary | std::ios::out))
     {
         std::cout << "Open file " << filename << " for write failed\\n";
         return 1;
     }
     fb.sputn(reinterpret_cast<char*>(&d), sizeof d);
     fb.close();

     // open file for reading
     double d2 = 0.0;
     if (!fb.open(filename, std::ios::binary | std::ios::in))
     {
         std::cout << "Open file " << filename << " for read failed\\n";
         return 1;
     }

     auto got = fb.sgetn(reinterpret_cast<char*>(&d2), sizeof d2);
     if (sizeof(d2) != got)
         std::cout << "Read of " << filename << " failed\\n";
     else
         std::cout << "Read back from file: " << d2 << '\\n';
 }

.SH Output:

 Read back from file: 3.14

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to           Behavior as published              Correct behavior
   LWG 596 C++98      open() could not open files in append     can open in append mode
                      mode

.SH See also

   is_open checks if the associated file is open
           \fI(public member function)\fP
   close   flushes the put area buffer and closes the associated file
           \fI(public member function)\fP
